<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Declaring and registering test cases with datasets</title>
<link rel="stylesheet" href="../../../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../../index.html" title="Boost.Test">
<link rel="up" href="../test_case_generation.html" title="Data-driven test cases">
<link rel="prev" href="datasets.html" title="Datasets">
<link rel="next" href="operations.html" title="Operations on dataset">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="datasets.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_case_generation.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="operations.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="boost_test.tests_organization.test_cases.test_case_generation.datasets_auto_registration"></a><a class="link" href="datasets_auto_registration.html" title="Declaring and registering test cases with datasets">Declaring
          and registering test cases with datasets</a>
</h5></div></div></div>
<p>
            In order to declare and register a data-driven test-case, the macros
            <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset.html" title="BOOST_DATA_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE</span></code></a> or <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset_fixture.html" title="BOOST_DATA_TEST_CASE_F"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE_F</span></code></a> should
            be used. Those two forms are equivalent, with the difference that <code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE_F</span></code> supports fixtures.
          </p>
<p>
            Those macros are variadic and can be used in the following forms:
          </p>
<pre class="programlisting"><a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset.html" title="BOOST_DATA_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE</span></code></a><span class="special">(</span><span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* dataset1 of arity 1 */</span> <span class="special">}</span>
<span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">,</span> <span class="identifier">var1</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* datasets of arity 1 */</span> <span class="special">}</span>
<span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">,</span> <span class="identifier">var1</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">varN</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* datasets of arity N  */</span> <span class="special">}</span>

<a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset_fixture.html" title="BOOST_DATA_TEST_CASE_F"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE_F</span></code></a><span class="special">(</span><span class="identifier">fixture</span><span class="special">,</span> <span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* dataset1 of arity 1 with fixture */</span> <span class="special">}</span>
<span class="identifier">BOOST_DATA_TEST_CASE_F</span><span class="special">(</span><span class="identifier">fixture</span><span class="special">,</span> <span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">,</span> <span class="identifier">var1</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* dataset1 of arity 1 with fixture */</span> <span class="special">}</span>
<span class="identifier">BOOST_DATA_TEST_CASE_F</span><span class="special">(</span><span class="identifier">fixture</span><span class="special">,</span> <span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">,</span> <span class="identifier">var1</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">varN</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* dataset1 of arity N with fixture */</span> <span class="special">}</span>
</pre>
<p>
            The first form of the macro is for datasets of arity 1. The value of
            the sample being executed by the test body is available through the automatic
            variable <code class="computeroutput"><span class="identifier">sample</span></code> (<code class="computeroutput"><span class="identifier">xrange</span></code> is as its name suggests a range
            of values):
          </p>
<pre class="programlisting"><span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case_arity1_implicit</span><span class="special">,</span> <span class="identifier">data</span><span class="special">::</span><span class="identifier">xrange</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">((</span><span class="identifier">sample</span> <span class="special">&lt;=</span> <span class="number">4</span> <span class="special">&amp;&amp;</span> <span class="identifier">sample</span> <span class="special">&gt;=</span> <span class="number">0</span><span class="special">));</span>
<span class="special">}</span>
</pre>
<p>
            The second form is also for datasets of arity 1, but instead of the variable
            <code class="computeroutput"><span class="identifier">sample</span></code>, the current sample
            is brought into <code class="computeroutput"><span class="identifier">var1</span></code>:
          </p>
<pre class="programlisting"><span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case_arity1</span><span class="special">,</span> <span class="identifier">data</span><span class="special">::</span><span class="identifier">xrange</span><span class="special">(</span><span class="number">5</span><span class="special">),</span> <span class="identifier">my_var</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">((</span><span class="identifier">my_var</span> <span class="special">&lt;=</span> <span class="number">4</span> <span class="special">&amp;&amp;</span> <span class="identifier">my_var</span> <span class="special">&gt;=</span> <span class="number">0</span><span class="special">));</span>
<span class="special">}</span>
</pre>
<p>
            The third form is an extension of the previous form for datasets of arity
            <code class="computeroutput"><span class="identifier">N</span></code>. The sample being a
            polymorphic tuple, each of the variables <code class="computeroutput"><span class="identifier">var1</span></code>,
            ..., <code class="computeroutput"><span class="identifier">varN</span></code> corresponds
            to the index 1, ... <code class="computeroutput"><span class="identifier">N</span></code>
            of the the sample:
          </p>
<pre class="programlisting"><span class="comment">// The following definition of the dataset test case throws an exception before the</span>
<span class="comment">// test module starts (zip of non infinite or singleton datasets of different length)</span>
<span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case_arity2</span><span class="special">,</span> <span class="identifier">data</span><span class="special">::</span><span class="identifier">xrange</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> <span class="special">^</span> <span class="identifier">data</span><span class="special">::</span><span class="identifier">xrange</span><span class="special">(</span><span class="number">5</span><span class="special">),</span> <span class="identifier">apples</span><span class="special">,</span> <span class="identifier">potatoes</span><span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">((</span><span class="identifier">apples</span> <span class="special">&lt;=</span> <span class="number">1</span> <span class="special">&amp;&amp;</span> <span class="identifier">apples</span> <span class="special">&gt;=</span> <span class="number">0</span><span class="special">));</span>
  <span class="identifier">BOOST_TEST</span><span class="special">((</span><span class="identifier">potatoes</span> <span class="special">&lt;=</span> <span class="number">4</span> <span class="special">&amp;&amp;</span> <span class="identifier">potatoes</span> <span class="special">&gt;=</span> <span class="number">0</span><span class="special">));</span>
<span class="special">}</span>
</pre>
<p>
            The next three forms of declaration, with <code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE_F</span></code>,
            are equivalent to the previous ones, with the difference being in the
            support of a fixture that is execute before the test body for each sample.
            The fixture should follow the expected interface as detailed <a class="link" href="../../fixtures/models.html" title="Fixture models">here</a>.
          </p>
<p>
            The arity of the dataset and the number of variables should be exactly
            the same, the first form being a short-cut for the case of arity 1.
          </p>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
              A compilation-time check is performed on the coherence of the arity
              of the dataset and the number of variables <code class="computeroutput"><span class="identifier">var1</span></code>...
              <code class="computeroutput"><span class="identifier">varN</span></code>. For compilers
              <span class="bold"><strong>without C++11</strong></span> support, the maximal
              supported arity is controlled by the macro <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset.html" title="BOOST_DATA_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_TEST_DATASET_MAX_ARITY</span></code></a>,
              that can be overridden <span class="emphasis"><em>prior</em></span> to including the
              <span class="emphasis"><em>Unit Test Framework</em></span> headers.
            </p></td></tr>
</table></div>
<div class="caution"><table border="0" summary="Caution">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/src/images/caution.png"></td>
<th align="left">Caution</th>
</tr>
<tr><td align="left" valign="top"><p>
              The macros <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset.html" title="BOOST_DATA_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE</span></code></a> and
              <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset_fixture.html" title="BOOST_DATA_TEST_CASE_F"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE_F</span></code></a> are
              available only for compilers with support for <span class="bold"><strong>variadic
              macros</strong></span>.
            </p></td></tr>
</table></div>
<h5>
<a name="boost_test.tests_organization.test_cases.test_case_generation.datasets_auto_registration.h0"></a>
            <span class="phrase"><a name="boost_test.tests_organization.test_cases.test_case_generation.datasets_auto_registration.samples_and_test_tree"></a></span><a class="link" href="datasets_auto_registration.html#boost_test.tests_organization.test_cases.test_case_generation.datasets_auto_registration.samples_and_test_tree">Samples
            and test tree</a>
          </h5>
<p>
            It should be emphasized that those macros do not declare a single test
            case (as <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_auto_test_case.html" title="BOOST_AUTO_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_CASE</span></code></a> would do)
            but declare and register as many test cases as there are samples in the
            dataset given in argument. Each test case runs on exactly <span class="bold"><strong>one</strong></span>
            sample of the dataset.
          </p>
<p>
            More precisely, what
          </p>
<pre class="programlisting"><a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset.html" title="BOOST_DATA_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE</span></code></a><span class="special">(</span><span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">)</span></pre>
<p>
            does is the following:
          </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
                it registers a <span class="bold"><strong>test suite</strong></span> named
                "<code class="computeroutput"><span class="identifier">test_case_name</span></code>",
              </li>
<li class="listitem">
                it registers as many test cases as they are in "<code class="computeroutput"><span class="identifier">dataset</span></code>", each of which with
                the name corresponding to the index of the sample in the database
                prefixed by <code class="computeroutput"><span class="identifier">_</span></code> and
                starting at index <code class="computeroutput"><span class="number">0</span></code> ("<code class="computeroutput"><span class="identifier">_0</span></code>", "<code class="computeroutput"><span class="identifier">_1</span></code>",
                ... "<code class="computeroutput"><span class="identifier">_</span><span class="special">(</span><span class="identifier">N</span><span class="special">-</span><span class="number">1</span><span class="special">)</span></code>"
                where <code class="computeroutput"><span class="identifier">N</span></code> is the size
                of the dataset)
              </li>
</ul></div>
<p>
            This make it easy to:
          </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
                identify which sample is failing (say "<code class="computeroutput"><span class="identifier">test_case_name</span><span class="special">/</span><span class="identifier">_3</span></code>"),
              </li>
<li class="listitem">
                replay the test for one or several samples (or the full dataset)
                from the command line using the <a class="link" href="../../../runtime_config/test_unit_filtering.html" title="Test unit filtering">test
                filtering features</a> provided by the <span class="emphasis"><em>Unit Test Framework</em></span>,
              </li>
<li class="listitem">
                apply a <a class="link" href="../../decorators/explicit_decorator_declaration.html" title="Explicit decorator declaration">decorator</a>
                to each individual test cases of the dataset, as the decorator would
                apply to the test suite.
              </li>
</ul></div>
<p>
            Exactly as regular test cases, each test case (associated to a specific
            sample) is executed in <span class="emphasis"><em>monitored manner</em></span>:
          </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
                the test execution are independent: if an error occurs for one sample,
                the remaining samples execution is not affected,
              </li>
<li class="listitem">
                in case of error, the <a class="link" href="../../../test_output/test_tools_support_for_logging/contexts.html" title="Contexts">context</a>
                along with the index of the sample within which the error occurred
                is reported in the <a class="link" href="../../../test_output.html" title="Controlling outputs">log</a>.
                This context contains the sample names and values for which the test
                failed, which would ease the debugging.
              </li>
</ul></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2022 Boost.Test contributors<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="datasets.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_case_generation.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="operations.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
